.TH lha_startapp 1 "27 January 2009" "TrueCL Commands"

.SH NAME
lha_startapp \- Start an application running in the Cluster

.SH SYNOPSES
.TS
l l.
clreq	[\fB-N|--node\fP \fIX\fP] [\fB-A|--application\fP \fIA\fP] [\fB-timeout\fP \fIN\fP]
	[\fB--fsonly\fP] [\fB--allow_invalid\fP] [\fB--nocleanup\fP] [\fB--force\fP]
	[\fB--allow_stale\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_startapp(1)\fP command is used to start applications running in the cluster.
If the application is already running, in the process or starting or stopping then the 
command will fail with a suitable error message. TrueCL is clustering for high availability
only currently; it does not support running the same application on multiple nodes at the
same time.

Although their are many arguments the command typically to start an application is
straightforward:

.TS
l.
lha_startapp -A appname
.TE

.SH ARGUMENTS
.TP 8
--application
This is the name of the application to start in the cluster. This is the only
mandatory argument. For an application to be started it must have been validated,
see the \fIlha_buildapp(1)\fP for details if this is not the case.

.TP
--node
By default the command will use the current node as a node to host the
application - if it is suitable. This argument allows the application
to be started on the named node - though only if suitable.

If the argument is given, but the node is not valid for the application the
command will abort with a suitable error message. If the argument is not
given, but the current node is not suitable, then a RANDOM suitable node will
be selected for the application to be started on.

.TP
--force
This argument allows the application to be started when normally the
safe-guards or the cluster state would not allow it. If an application
absolutely must be started then use this argument, though it should be
considered as a 'last resort' - and not used in normal circumstances.

.TP
--timeout
The amount of time to wait for certain responses to requests that are 
necessary for the application to be started.  If this is not specified the
value is taken from the 'starttimeout' attribute defined for the 
application. If such an attribute is not currently defined it will 
default to 60 [seconds].

.TP
--fsonly
Do not perform the full application start-up - run the application in
maintenance mode. All storage is made available on the node in question,
but the IP addresses [if any] are not allocated, the application [if any] is not
started, and no monitors [if any] are run.

This is useful if you wish to modify the application or application storage
without the application being run and thus risk interfere by users of
the application.

.TP
--livenodes
Give a comma-separated list of nodes to consider as suitable for hosting
the specified application. It is not expected that this will be used on
interactive commands; instead it is used by the cluster daemons when
restarting applications due to failures in the cluster infrastructure.

.TP
--allow_invalid
If an application has not been validated after making changes to it the
\fIlha_startapp(1)\fP command will, by default, refuse to make an attempt
to start the application. This argument causes the command to ignore the
fact that the application has been changed and no attempt to validate the
new configuration has yet been performed.

.TP
--nocleanup
By default if the start-up of the specified application fails all 
resources allocated during the start-up process are cleared down and the
application left in a STOPPED state. When this flag is used no clean-up
is attempted and the application state is left as it was when the failure
occurred. This is particularly useful when attempting to track down 
software problems.

.TP
--allow_stale
This flag is useful when an application is making use of replicated storage.
By default if the storage accessible to the application is considered 'stale'
then the application will refuse to start. Using this flag will force the
data to be considered active; resulting in it over-writing other copies 
when they become available.

It is very unlikely this flag will be needed in typical day-to-day use of 
the cluster software.

.TP
--debug
Start the cluster daemons in debug mode - the log files for each of the 
daemons will produce significantly more output than normal. This is not 
typically required and should only be done if problems in cluster formation
occur.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of cluster formation. This is the recommended flag if
the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during cluster formation.

.SH OUTPUT
In verbose mode the utility will show the application start-up in several
distinct steps - some of which will take longer than others. In particular
the storage configuration and application start-up are areas where the
time taken and output generated can differ significant depending on
how the application is configured.

.SH EXIT CODES
If the application is started as expected, a return code of '0' will be given, 
indicating successful. Otherwise a failure is indicated with a return code of '1'.
If a failure does occur then a suitable error message should be shown on the
standard output device too.

.SH FILES
The utility uses standard error and output for all messages. When the 
applications start-up occurs, the following log files are used for
any output generated by the scripts:

.TS
l l.
clreqd.stdout	Will contain any standard output text for the application.
clreqd.stderr	Will contain any error output text for the application.
.TE

.SH NOTES
The use of a random node if no node is specified and the current node is 
not valid is subject to change to make better use of application load
balancing policy at some point in the future.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2008, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_destroyapp(1),
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_buildapp(1),
.BR lha_modapp(1),
.BR lha_stopapp(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

